# Pug 插件

import { SourceCode } from 'rspress/theme';

<SourceCode href="https://github.com/web-infra-dev/rsbuild/tree/main/packages/plugin-pug" />

Pug 插件提供了对 Pug 模板引擎的支持。Pug 是一款健壮、灵活、功能丰富的模板引擎，专门为 Node.js 平台开发。

## 快速开始

### 安装插件

你可以通过如下的命令安装插件:

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs command="add @rsbuild/plugin-pug -D" />

### 注册插件

你可以在 `rsbuild.config.ts` 文件中注册插件：

```ts title="rsbuild.config.ts"
import { pluginPug } from '@rsbuild/plugin-pug';

export default {
  plugins: [pluginPug()],
};
```

### 使用 Pug 模板

插件注册完成后，Rsbuild 会自动解析后缀为 `.pug` 的模板文件，并使用 Pug 模板引擎对其进行编译。

比如，首先创建一个 `src/index.pug` 文件，并通过 `html.template` 指向该文件：

```ts title="rsbuild.config.ts"
export default {
  html: {
    template: './src/index.pug',
  },
};
```

然后在 `index.pug` 模板中使用 Pug 语法即可：

```html
<!-- 输入  -->
p Hello #{text}!

<!-- 输出 -->
<p>Hello World!</p>
```

请阅读 [Pug 文档](https://pugjs.org/) 来了解 Pug 的完整用法。

### 在 Vue 中使用

当你使用 Vue 时，可以在 `.vue` 文件的 template 中使用 Pug 语法：

```vue title="App.vue"
<template lang="pug">
button.my-button(@click='count++') Count is: {{ count }}
</template>

<script>
import { ref } from 'vue';

export default {
  setup() {
    const count = ref(0);

    return {
      count,
    };
  },
};
</script>
```

## 选项

### pugOptions

用于设置 Pug 的编译选项，详细选项请查看 [Pug API Reference](https://pugjs.org/api/reference.html#options)。

- **类型：** `Object | Function | undefined`
- **默认值：**

```ts
const defaultOptions = {
  doctype: 'html',
  compileDebug: false,
};
```

- **示例一：** 传入一个配置对象，该对象会和插件内部的默认选项通过 `Object.assign` 合并。

```ts
pluginPug({
  pugOptions: {
    doctype: 'xml',
  },
});
```

- **示例二：** 传入一个配置函数，默认配置会作为第一个参数传入，你可以直接修改配置对象，也可以返回一个值作为最终结果。

```ts
pluginPug({
  pugOptions(config) {
    config.doctype = 'xml';
  },
});
```
